home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / pcl / docs.lha / cmu-user / cmu-user.info-8 < prev    next >
Text File  |  1992-08-05  |  50KB  |  1,395 lines
  1. Info file: cmu-user.info,    -*-Text-*-
  2. produced by latexinfo-format-buffer
  3. from file: cmu-user.tex
  4.  
  5.  
  6. 
  7. File: cmu-user.info  Node: With Object Sets, Prev: Without Object Sets, Up: Using SERVE-EVENT with the CLX Interface to X
  8.  
  9. With Object Sets
  10. ----------------
  11.  
  12. This section discusses the use of object sets and `system:serve-event'
  13. to handle CLX events.  This is necessary when a single X application has
  14. distinct windows that want to handle the same events in different ways.
  15. Basically, you need some way of asking for a given window which way you
  16. want to handle some event because this event is handled differently
  17. depending on the window.  Object sets provide this feature.
  18.  
  19. For each CLX event-key symbol-name XXX (for example, KEY-PRESS), there
  20. is a function `serve-'XXX of two arguments, an object set and a
  21. function.  The `serve-'XXX function establishes the function as the
  22. handler for the :XXX event in the object set.  Recall from section *Note
  23. Object Sets::, `system:add-xwindow-object' associates some Lisp object
  24. with a CLX window in an object set.  When `system:serve-event' notices
  25. activity on a window, it calls the function given to
  26. `ext:enable-clx-event-handling'.  If this function is
  27. `ext:object-set-event-handler', it calls the function given to
  28. `serve-'XXX, passing the object given to `system:add-xwindow-object' and
  29. the event's slots as well as a couple other arguments described below.
  30.  
  31. To use object sets in this way:
  32.      
  33.    * Create an object set.
  34.      
  35.    * Define some operations on it using the `serve-'XXX functions.
  36.      
  37.    * Add an object for every window on which you receive requests.  This
  38.      can be the CLX window itself or some structure more meaningful to
  39.      your application.
  40.      
  41.    * Call `system:serve-event' to service an X event.
  42.  
  43.  
  44.  
  45.  
  46.  -- Function: object-set-event-handler DISPLAY
  47.  
  48.      This function is a suitable argument to `ext:enable-clx-event-handling'.  The
  49.      actual event handlers defined for particular events within a given object set
  50.      must take an argument for every slot in the appropriate event.  In addition to
  51.      the event slots, `ext:object-set-event-handler' passes the following
  52.      arguments: 
  53.           
  54.         * The object, as established by `system:add-xwindow-object', on
  55.           which the event occurred.
  56.           
  57.         * event-key, see `xlib:event-case'.
  58.           
  59.         * send-event-p, see `xlib:event-case'.
  60.      
  61.      
  62.      Describing any `ext:serve-'EVENT-KEY-NAME function, where
  63.      EVENT-KEY-NAME is an event-key symbol-name (for example,
  64.      `ext:serve-key-press'), indicates exactly what all the arguments
  65.      are in their correct order.
  66.      
  67.      
  68.      When creating an object set for use with
  69.      `ext:object-set-event-handler', specify
  70.      `ext:default-clx-event-handler' as the default handler for events
  71.      in that object set.  If no default handler is specified, and the
  72.      system invokes the default default handler, it will cause an error
  73.      since this function takes arguments suitable for handling port
  74.      messages.
  75.  
  76.  
  77.  
  78. 
  79. File: cmu-user.info  Node: A SERVE-EVENT Example, Prev: Using SERVE-EVENT with the CLX Interface to X, Up: Event Dispatching with SERVE-EVENT
  80.  
  81. A SERVE-EVENT Example
  82. =====================
  83.  
  84. This section contains two examples using `system:serve-event'.  The
  85. first one does not use object sets, and the second, slightly more
  86. complicated one does.
  87.  
  88.  
  89. * Menu:
  90.  
  91. * Without Object Sets Example::  
  92. * With Object Sets Example::    
  93.  
  94.  
  95. 
  96. File: cmu-user.info  Node: Without Object Sets Example, Prev: A SERVE-EVENT Example, Up: A SERVE-EVENT Example, Next: With Object Sets Example
  97.  
  98. Without Object Sets Example
  99. ---------------------------
  100.  
  101. This example defines an input handler for a CLX display connection.  It
  102. only recognizes :key-press events.  The body of the example loops over
  103. `system:serve-event' to get input.
  104.  
  105.      
  106.      (in-package "SERVER-EXAMPLE")
  107.      
  108.      (defun my-input-handler (display)
  109.        (xlib:event-case (display :timeout 0)
  110.          (:key-press (event-window code state)
  111.           (format t "KEY-PRESSED (Window = ~D) = ~S.~%"
  112.                        (xlib:window-id event-window)
  113.                   ;; See Hemlock Command Implementor's Manual for convenient
  114.                   ;; input mapping function.
  115.                   (ext:translate-character display code state))
  116.            ;; Make XLIB:EVENT-CASE discard the event.
  117.            t)))
  118.  
  119.      
  120.      (defun server-example ()
  121.        "An example of using the SYSTEM:SERVE-EVENT function and object sets to
  122.         handle CLX events."
  123.        (let* ((display (ext:open-clx-display))
  124.               (screen (display-default-screen display))
  125.               (black (screen-black-pixel screen))
  126.               (white (screen-white-pixel screen))
  127.               (window (create-window :parent (screen-root screen)
  128.                                      :x 0 :y 0 :width 200 :height 200
  129.                                      :background white :border black
  130.                                      :border-width 2
  131.                                      :event-mask
  132.                                      (xlib:make-event-mask :key-press))))
  133.          ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves.
  134.          (unwind-protect
  135.              (progn
  136.                ;; Enable event handling on the display.
  137.                (ext:enable-clx-event-handling display #'my-input-handler)
  138.                ;; Map the windows to the screen.
  139.                (map-window window)
  140.                ;; Make sure we send all our requests.
  141.                (display-force-output display)
  142.                ;; Call serve-event for 100,000 events or immediate timeouts.
  143.                (dotimes (i 100000) (system:serve-event)))
  144.            ;; Disable event handling on this display.
  145.            (ext:disable-clx-event-handling display)
  146.            ;; Get rid of the window.
  147.            (destroy-window window)
  148.            ;; Pick off any events the X server has already queued for our
  149.            ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer
  150.            ;; prepared to handle events for us.
  151.            (loop
  152.             (unless (deleting-window-drop-event *display* window)
  153.              (return)))
  154.            ;; Close the display.
  155.            (xlib:close-display display))))
  156.      
  157.      (defun deleting-window-drop-event (display win)
  158.        "Check for any events on win.  If there is one, remove it from the
  159.         event queue and return t; otherwise, return nil."
  160.        (xlib:display-finish-output display)
  161.        (let ((result nil))
  162.          (xlib:process-event
  163.           display :timeout 0
  164.           :handler #'(lambda (&key event-window &allow-other-keys)
  165.                        (if (eq event-window win)
  166.                            (setf result t)
  167.                            nil)))
  168.          result))
  169.  
  170.  
  171.  
  172. 
  173. File: cmu-user.info  Node: With Object Sets Example, Prev: Without Object Sets Example, Up: A SERVE-EVENT Example
  174.  
  175. With Object Sets Example
  176. ------------------------
  177.  
  178. This example involves more work, but you get a little more for your
  179. effort.  It defines two objects, `input-box' and `slider', and
  180. establishes a :key-press handler for each object, `key-pressed' and
  181. `slider-pressed'.  We have two object sets because we handle events on
  182. the windows manifesting these objects differently, but the events come
  183. over the same display connection.
  184.  
  185.      
  186.      (in-package "SERVER-EXAMPLE")
  187.      
  188.      (defstruct (input-box (:print-function print-input-box)
  189.                            (:constructor make-input-box (display window)))
  190.        "Our program knows about input-boxes, and it doesn't care how they
  191.         are implemented."
  192.        display        ; The CLX display on which my input-box is displayed.
  193.        window)        ; The CLX window in which the user types.
  194.      ;;;
  195.      (defun print-input-box (object stream n)
  196.        (declare (ignore n))
  197.        (format stream "#<Input-Box ~S>" (input-box-display object)))
  198.      
  199.      (defvar *input-box-windows*
  200.              (system:make-object-set "Input Box Windows"
  201.                                      #'ext:default-clx-event-handler))
  202.      
  203.      (defun key-pressed (input-box event-key event-window root child
  204.                          same-screen-p x y root-x root-y modifiers time
  205.                          key-code send-event-p)
  206.        "This is our :key-press event handler."
  207.        (declare (ignore event-key root child same-screen-p x y
  208.                         root-x root-y time send-event-p))
  209.        (format t "KEY-PRESSED (Window = ~D) = ~S.~%"
  210.                (xlib:window-id event-window)
  211.                ;; See Hemlock Command Implementor's Manual for convenient
  212.                ;; input mapping function.
  213.                (ext:translate-character (input-box-display input-box)
  214.                                           key-code modifiers)))
  215.      ;;;
  216.      (ext:serve-key-press *input-box-windows* #'key-pressed)
  217.  
  218.      
  219.      (defstruct (slider (:print-function print-slider)
  220.                         (:include input-box)
  221.                         (:constructor %make-slider
  222.                                          (display window window-width max)))
  223.        "Our program knows about sliders too, and these provide input values
  224.         zero to max."
  225.        bits-per-value  ; bits per discrete value up to max.
  226.        max)            ; End value for slider.
  227.      ;;;
  228.      (defun print-slider (object stream n)
  229.        (declare (ignore n))
  230.        (format stream "#<Slider ~S  0..~D>"
  231.                (input-box-display object)
  232.                (1- (slider-max object))))
  233.      ;;;
  234.      (defun make-slider (display window max)
  235.        (%make-slider display window
  236.                        (truncate (xlib:drawable-width window) max)
  237.                      max))
  238.      
  239.      (defvar *slider-windows*
  240.              (system:make-object-set "Slider Windows"
  241.                                      #'ext:default-clx-event-handler))
  242.      
  243.      (defun slider-pressed (slider event-key event-window root child
  244.                             same-screen-p x y root-x root-y modifiers time
  245.                             key-code send-event-p)
  246.        "This is our :key-press event handler for sliders.  Probably this is
  247.         a mouse thing, but for simplicity here we take a character typed."
  248.        (declare (ignore event-key root child same-screen-p x y
  249.                         root-x root-y time send-event-p))
  250.        (format t "KEY-PRESSED (Window = ~D) = ~S  -->  ~D.~%"
  251.                (xlib:window-id event-window)
  252.                ;; See Hemlock Command Implementor's Manual for convenient
  253.                ;; input mapping function.
  254.                (ext:translate-character (input-box-display slider)
  255.                                           key-code modifiers)
  256.                (truncate x (slider-bits-per-value slider))))
  257.      ;;;
  258.      (ext:serve-key-press *slider-windows* #'slider-pressed)
  259.  
  260.      
  261.      (defun server-example ()
  262.        "An example of using the SYSTEM:SERVE-EVENT function and object sets to
  263.         handle CLX events."
  264.        (let* ((display (ext:open-clx-display))
  265.               (screen (display-default-screen display))
  266.               (black (screen-black-pixel screen))
  267.               (white (screen-white-pixel screen))
  268.               (iwindow (create-window :parent (screen-root screen)
  269.                                       :x 0 :y 0 :width 200 :height 200
  270.                                       :background white :border black
  271.                                       :border-width 2
  272.                                       :event-mask
  273.                                       (xlib:make-event-mask :key-press)))
  274.               (swindow (create-window :parent (screen-root screen)
  275.                                       :x 0 :y 300 :width 200 :height 50
  276.                                       :background white :border black
  277.                                       :border-width 2
  278.                                       :event-mask
  279.                                       (xlib:make-event-mask :key-press)))
  280.               (input-box (make-input-box display iwindow))
  281.               (slider (make-slider display swindow 15)))
  282.          ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves.
  283.          (unwind-protect
  284.              (progn
  285.                ;; Enable event handling on the display.
  286.                (ext:enable-clx-event-handling display
  287.                                               #'ext:object-set-event-handler)
  288.                ;; Add the windows to the appropriate object sets.
  289.                (system:add-xwindow-object iwindow input-box
  290.                                             *input-box-windows*)
  291.                (system:add-xwindow-object swindow slider
  292.                                             *slider-windows*)
  293.                ;; Map the windows to the screen.
  294.                (map-window iwindow)
  295.                (map-window swindow)
  296.                ;; Make sure we send all our requests.
  297.                (display-force-output display)
  298.                ;; Call server for 100,000 events or immediate timeouts.
  299.                (dotimes (i 100000) (system:serve-event)))
  300.            ;; Disable event handling on this display.
  301.            (ext:disable-clx-event-handling display)
  302.            (delete-window iwindow display)
  303.            (delete-window swindow display)
  304.            ;; Close the display.
  305.            (xlib:close-display display))))
  306.  
  307.      
  308.      (defun delete-window (window display)
  309.        ;; Remove the windows from the object sets before destroying them.
  310.        (system:remove-xwindow-object window)
  311.        ;; Destroy the window.
  312.        (destroy-window window)
  313.        ;; Pick off any events the X server has already queued for our
  314.        ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer
  315.        ;; prepared to handle events for us.
  316.        (loop
  317.         (unless (deleting-window-drop-event display window)
  318.           (return))))
  319.      
  320.      (defun deleting-window-drop-event (display win)
  321.        "Check for any events on win.  If there is one, remove it from the
  322.         event queue and return t; otherwise, return nil."
  323.        (xlib:display-finish-output display)
  324.        (let ((result nil))
  325.          (xlib:process-event
  326.           display :timeout 0
  327.           :handler #'(lambda (&key event-window &allow-other-keys)
  328.                        (if (eq event-window win)
  329.                            (setf result t)
  330.                            nil)))
  331.          result))
  332.  
  333.  
  334.  
  335.  
  336. 
  337. File: cmu-user.info  Node: Alien Objects, Prev: Event Dispatching with SERVE-EVENT, Up: Top, Next: Interprocess Communication under LISP
  338.  
  339. Alien Objects
  340. *************
  341.  
  342.                  By Robert MacLachlan and William Lott
  343.  
  344.  
  345. * Menu:
  346.  
  347. * Introduction to Aliens::      
  348. * Alien Types::                 
  349. * Alien Operations::            
  350. * Alien Variables::             
  351. * Alien Data Structure Example::  
  352. * Loading Unix Object Files::   
  353. * Alien Function Calls::        
  354. * Step-by-Step Alien Example::  
  355.  
  356.  
  357. 
  358. File: cmu-user.info  Node: Introduction to Aliens, Prev: Alien Objects, Up: Alien Objects, Next: Alien Types
  359.  
  360. Introduction to Aliens
  361. ======================
  362.  
  363.  
  364. Because of Lisp's emphasis on dynamic memory allocation and garbage
  365. collection, Lisp implementations use unconventional memory representations
  366. for objects.  This representation mismatch creates problems when a Lisp
  367. program must share objects with programs written in another language.  There
  368. are three different approaches to establishing communication:
  369.    * The burden can be placed on the foreign program (and programmer) by
  370.      requiring the use of Lisp object representations.  The main
  371.      difficulty with this approach is that either the foreign program
  372.      must be written with Lisp interaction in mind, or a substantial
  373.      amount of foreign "glue" code must be written to perform the
  374.      translation.
  375.      
  376.    * The Lisp system can automatically convert objects back and forth
  377.      between the Lisp and foreign representations.  This is convenient,
  378.      but translation becomes prohibitively slow when large or complex
  379.      data structures must be shared.
  380.      
  381.    * The Lisp program can directly manipulate foreign objects through
  382.      the use of extensions to the Lisp language.  Most Lisp systems make
  383.      use of this approach, but the language for describing types and
  384.      expressing accesses is often not powerful enough for complex
  385.      objects to be easily manipulated.
  386.  
  387. CMU Common Lisp relies primarily on the automatic conversion and direct
  388. manipulation approaches: Aliens of simple scalar types are automatically
  389. converted, while complex types are directly manipulated in their foreign
  390. representation.  Any foreign objects that can't automatically be
  391. converted into Lisp values are represented by objects of type
  392. `alien-value'.  Since Lisp is a dynamically typed language, even foreign
  393. objects must have a run-time type; this type information is provided by
  394. encapsulating the raw pointer to the foreign data within an
  395. `alien-value' object.
  396.  
  397. The Alien type language and operations are most similar to those of the
  398. C language, but Aliens can also be used when communicating with most
  399. other languages that can be linked with C.
  400.  
  401.  
  402. 
  403. File: cmu-user.info  Node: Alien Types, Prev: Introduction to Aliens, Up: Alien Objects, Next: Alien Operations
  404.  
  405. Alien Types
  406. ===========
  407.  
  408.  
  409. Alien types have a description language based on nested list structure.  For
  410. example:
  411.      
  412.      struct foo {
  413.          int a;
  414.          struct foo *b[100];
  415.      };
  416.  
  417. has the corresponding Alien type:
  418.      
  419.      (struct foo
  420.        (a int)
  421.        (b (array (* (struct foo)) 100)))
  422.  
  423.  
  424.  
  425. * Menu:
  426.  
  427. * Defining Alien Types::        
  428. * Alien Types and Lisp Types::  
  429. * Alien Type Specifiers::       
  430. * The C-Call Package::          
  431.  
  432.  
  433. 
  434. File: cmu-user.info  Node: Defining Alien Types, Prev: Alien Types, Up: Alien Types, Next: Alien Types and Lisp Types
  435.  
  436. Defining Alien Types
  437. --------------------
  438.  
  439.  
  440. Types may be either named or anonymous.  With structure and union types, the
  441. name is part of the type specifier, allowing recursively defined types such as:
  442.      
  443.      (struct foo (a (* (struct foo))))
  444.  
  445. An anonymous structure or union type is specified by using the name nil.
  446. The with-alien ? macro defines a local scope which "captures" any named
  447. type definitions.  Other types are not inherently named, but can be
  448. given named abbreviations using `def-alien-type'.
  449.  
  450.  
  451.  -- Macro: def-alien-type name type
  452.  
  453.      This macro globally defines NAME as a shorthand for the Alien type
  454.      TYPE.  When introducing global structure and union type
  455.      definitions, NAME may be nil, in which case the name to define is
  456.      taken from the type's name.
  457.  
  458.  
  459.  
  460. 
  461. File: cmu-user.info  Node: Alien Types and Lisp Types, Prev: Defining Alien Types, Up: Alien Types, Next: Alien Type Specifiers
  462.  
  463. Alien Types and Lisp Types
  464. --------------------------
  465.  
  466.  
  467. The Alien types form a subsystem of the CMU Common Lisp type system.  An `alien'
  468. type specifier provides a way to use any Alien type as a Lisp type
  469. specifier.  For example
  470.      
  471.      (typep foo '(alien (* int)))
  472.  
  473. can be used to determine whether `foo' is a pointer to an `int'.
  474. `alien' type specifiers can be used in the same ways as ordinary type
  475. specifiers (like `string'.)  Alien type declarations are subject to the same
  476. precise type checking as any other declaration (section
  477. *Note Precise Type Checking::.)
  478.  
  479. Note that the Alien type system overlaps with normal Lisp type
  480. specifiers in some cases.  For example, the type specifier `(alien
  481. single-float)' is identical to `single-float', since Alien floats are
  482. automatically converted to Lisp floats.  When `type-of' is called on an
  483. Alien value that is not automatically converted to a Lisp value, then it
  484. will return an `alien' type specifier.
  485.  
  486. 
  487. File: cmu-user.info  Node: Alien Type Specifiers, Prev: Alien Types and Lisp Types, Up: Alien Types, Next: The C-Call Package
  488.  
  489. Alien Type Specifiers
  490. ---------------------
  491.  
  492.  
  493. Some Alien type names are CMU Common Lispsymbols, but the names are
  494. still exported from the `alien' package, so it is legal to say
  495. `alien:single-float'.  These are the basic Alien type specifiers: 
  496.  
  497.  
  498.  -- Alien type: TYPE
  499.      A pointer to an object of the specified TYPE.  If TYPE is true,
  500.      then it means a pointer to anything, similar to "`void *'" in ANSI C.
  501.      Currently, the only way to detect a null pointer is:
  502.           
  503.           (zerop (sap-int (alien-sap PTR)))
  504.      
  505.      *Note System Area Pointers::
  506.  
  507.  
  508.  
  509.  -- Alien type: array TYPE {DIMENSION}*
  510.      An array of the specified DIMENSIONS, holding elements of type
  511.      TYPE.  Note that `(* int)' and `(array int)' are considered to be
  512.      different types when type checking is done; pointer and array types
  513.      must be explicitly coerced using `cast'.
  514.      
  515.      Arrays are accessed using `deref', passing the indices as
  516.      additional arguments.  Elements are stored in column-major order
  517.      (as in C), so the first dimension determines only the size of the
  518.      memory block, and not the layout of the higher dimensions.  An
  519.      array whose first dimension is variable may be specified by using
  520.      nil as the first dimension.  Fixed-size arrays can be allocated as
  521.      array elements, structure slots or `with-alien' variables.  Dynamic
  522.      arrays can only be allocated using make-alien ?.
  523.  
  524.  
  525.  
  526.  
  527.  -- Alien type: struct NAME 
  528.                             {(FIELD TYPE [BITS])}*
  529.      A structure type with the specified NAME and FIELDS.  Fields are
  530.      allocated at the same positions used by the implementation's C
  531.      compiler.  BITS is intended for C-like bit field support, but is
  532.      currently unused.  If NAME is false, then the type is anonymous.
  533.      
  534.      If a named Alien `struct' specifier is passed to def-alien-type
  535.      *Note Defining Alien Types:: or with-alien ?, then this defines,
  536.      respectively, a new global or local Alien structure type.  If no
  537.      FIELDS are specified, then the fields are taken from the current
  538.      (local or global) Alien structure type definition of NAME.
  539.  
  540.  
  541.  
  542.  -- Alien type: union NAME 
  543.                            {(FIELD TYPE [BITS])}*
  544.      Similar to `struct', but defines a union type.  All fields are
  545.      allocated at the same offset, and the size of the union is the size
  546.      of the largest field.  The programmer must determine which field is
  547.      active from context.
  548.  
  549.  
  550.  
  551.  -- Alien type: enum NAME {SPEC}*
  552.      An enumeration type that maps between integer values and keywords.  If
  553.      NAME is false, then the type is anonymous.  Each SPEC is either
  554.      a keyword, or a list `(KEYWORD VALUE)'.  If INTEGER is
  555.      not supplied, then it defaults to one greater than the value for the preceding
  556.      spec (or to zero if it is the first spec.)
  557.  
  558.  
  559.   
  560.  -- Alien type: signed [BITS]
  561.      A signed integer with the specified number of bits precision.  The
  562.      upper limit on integer precision is determined by the machine's
  563.      word size.  If no size is specified, the maximum size will be used.
  564.  
  565.  
  566.   
  567.  -- Alien type: integer [BITS]
  568.      Identical to `signed' --- the distinction between `signed' and
  569.      `integer' is purely stylistic.
  570.  
  571.  
  572.  
  573.  -- Alien type: unsigned [BITS]
  574.      Like `signed', but specifies an unsigned integer.
  575.  
  576.  
  577.  
  578.  -- Alien type: boolean [BITS]
  579.      Similar to an enumeration type that maps `0' to false and all other
  580.      values to true.  BITS determines the amount of storage allocated to
  581.      hold the truth value.
  582.  
  583.  
  584.  
  585.  -- Alien type: single-float
  586.      A floating-point number in IEEE single format.
  587.  
  588.  
  589.  
  590.  -- Alien type: double-float
  591.      A floating-point number in IEEE double format.
  592.  
  593.  
  594.  
  595.  -- Alien type: function RESULT-TYPE {ARG-TYPE}*
  596.      A Alien function that takes arguments of the specified ARG-TYPES and
  597.      returns a result of type RESULT-TYPE.  Note that the only context where
  598.      a `function' type is directly specified is in the argument to
  599.      `alien-funcall' (see section ?.)  In all other contexts,
  600.      functions are represented by function pointer types: `(* (function
  601. ...))'.  
  602.  
  603.  
  604.  -- Alien type: system-area-pointer
  605.      A pointer which is represented in Lisp as a `system-area-pointer' object
  606.      (*Note System Area Pointers::.)
  607.  
  608.  
  609. 
  610. File: cmu-user.info  Node: The C-Call Package, Prev: Alien Type Specifiers, Up: Alien Types
  611.  
  612. The C-Call Package
  613. ------------------
  614.  
  615.  
  616. The `c-call' package exports these type-equivalents to the C type of the
  617. same name: `char', `short', `int', `long', `unsigned-char',
  618. `unsigned-short', `unsigned-int', `unsigned-long', `float', `double'.
  619. `c-call' also exports these types:
  620.  
  621.  
  622.  -- Alien type: void
  623.      This type is used in function types to declare that no useful value
  624.      is returned.  Evaluation of an `alien-funcall' form will return
  625.      zero values.
  626.  
  627.  
  628.  
  629.  -- Alien type: c-string
  630.      This type is similar to `(* char)', but is interpreted as a
  631.      null-terminated string, and is automatically converted into a Lisp
  632.      string when accessed.  If the pointer is C `NULL' (or 0), then
  633.      accessing gives Lisp false.
  634.      
  635.      Assigning a Lisp string to a `c-string' structure field or variable stores
  636.      the contents of the string to the memory already pointed to by that variable.
  637.      When an Alien of type `(* char)' is assigned to a `c-string', then
  638.      the `c-string' pointer is assigned to.  This allows `c-string'
  639.      pointers to be initialized.  For example:
  640.           
  641.           (def-alien-type nil (struct foo (str c-string)))
  642.           
  643.           (defun make-foo (str)
  644.             (let ((my-foo (make-alien (struct foo))))
  645.               (setf (slot my-foo 'str) (make-alien char (length str)))
  646.               (setf (slot my-foo 'str) str)
  647.               my-foo))
  648.      
  649.      Storing Lisp false writes C `NULL' to the `c-string' pointer.
  650.  
  651.  
  652.  
  653. 
  654. File: cmu-user.info  Node: Alien Operations, Prev: Alien Types, Up: Alien Objects, Next: Alien Variables
  655.  
  656. Alien Operations
  657. ================
  658.  
  659.  
  660. This section describes the basic operations on Alien values.
  661.  
  662. * Menu:
  663.  
  664. * Alien Access Operations::     
  665. * Alien Coercion Operations::   
  666. * Alien Dynamic Allocation::    
  667.  
  668.  
  669. 
  670. File: cmu-user.info  Node: Alien Access Operations, Prev: Alien Operations, Up: Alien Operations, Next: Alien Coercion Operations
  671.  
  672. Alien Access Operations
  673. -----------------------
  674.  
  675.  
  676.  
  677.  -- Function: deref POINTER-OR-ARRAY &restINDICES
  678.  
  679.      This function returns the value pointed to by an Alien pointer or
  680.      the value of an Alien array element.  If a pointer, an optional
  681.      single index can be specified to give the equivalent of C pointer
  682.      arithmetic; this index is scaled by the size of the type pointed
  683.      to.  If an array, the number of indices must be the same as the
  684.      number of dimensions in the array type.  `deref' can be set with
  685.      `setf' to assign a new value.
  686.  
  687.  
  688.  
  689.  -- Function: slot STRUCT-OR-UNION SLOT-NAME
  690.  
  691.      This function extracts the value of slot SLOT-NAME from the an Alien
  692.      `struct' or `union'.  If STRUCT-OR-UNION is a pointer to a
  693.      structure or union, then it is automatically dereferenced.  This can be
  694.      set with `setf' to assign a new value.  Note that SLOT-NAME
  695.      is evaluated, and need not be a compile-time constant (but only constant
  696.      slot accesses are efficiently compiled.)
  697.  
  698.  
  699. 
  700. File: cmu-user.info  Node: Alien Coercion Operations, Prev: Alien Access Operations, Up: Alien Operations, Next: Alien Dynamic Allocation
  701.  
  702. Alien Coercion Operations
  703. -------------------------
  704.  
  705.  
  706.  
  707.  -- Macro: addr ALIEN-EXPR
  708.  
  709.      This macro returns a pointer to the location specified by
  710.      ALIEN-EXPR, which must be either an Alien variable, a use of
  711.      `deref', a use of `slot', or a use of extern-alien ?.
  712.  
  713.  
  714.  
  715.  -- Macro: cast ALIEN NEW-TYPE
  716.  
  717.      This macro converts ALIEN to a new Alien with the specified
  718.      NEW-TYPE.  Both types must be an Alien pointer, array or function
  719.      type.  Note that the result is not `eq' to the argument, but does
  720.      refer to the same data bits.
  721.  
  722.  
  723.  
  724.  -- Macro: sap-alien SAP TYPE
  725.  
  726.  -- Function: alien-sap ALIEN-VALUE
  727.  
  728.      `sap-alien' converts SAP (a system area pointer *Note System Area
  729.      Pointers::) to an Alien value with the specified TYPE.  TYPE is not
  730.      evaluated.
  731.      
  732.      `alien-sap' returns the SAP which points to ALIEN-VALUE's data.
  733.      
  734.      The TYPE to `sap-alien' and the type of the ALIEN-VALUE to
  735.      `alien-sap' must some Alien pointer, array or record type.
  736.  
  737.  
  738. 
  739. File: cmu-user.info  Node: Alien Dynamic Allocation, Prev: Alien Coercion Operations, Up: Alien Operations
  740.  
  741. Alien Dynamic Allocation
  742. ------------------------
  743.  
  744.  
  745. Dynamic Aliens are allocated using the `malloc' library, so foreign code
  746. can call `free' on the result of `make-alien', and Lisp code can call
  747. `free-alien' on objects allocated by foreign code.
  748.  
  749.  
  750.  -- Macro: make-alien TYPE [SIZE]
  751.  
  752.      This macro returns a dynamically allocated Alien of the specified
  753.      TYPE (which is not evaluated.)  The allocated memory is not
  754.      initialized, and may contain arbitrary junk.  If supplied, SIZE is
  755.      an expression to evaluate to compute the size of the allocated object.
  756.      There are two major cases:
  757.         * When TYPE is an array type, an array of that type is
  758.           allocated and a POINTER to it is returned.  Note that you must use
  759.           `deref' to change the result to an array before you can use
  760.           `deref' to read or write elements:
  761.                
  762.                (defvar *foo* (make-alien (array char 10)))
  763.                
  764.                (type-of *foo*)
  765.                =>  (alien (* (array (signed 8) 10)))
  766.                
  767.                (setf (deref (deref foo) 0) 10)
  768.                =>  10
  769.           
  770.           If supplied, SIZE is used as the first dimension for the
  771.           array.
  772.           
  773.         * When TYPE is any other type, then then an object for that type
  774.           is allocated, and a POINTER to it is returned.  So
  775.           `(make-alien int)' returns a `(* int)'.  If SIZE is specified,
  776.           then a block of that many objects is allocated, with the
  777.           result pointing to the first one.
  778.      
  779.  
  780.  
  781.  
  782.  -- Function: free-alien ALIEN
  783.  
  784.      This function frees the storage for ALIEN (which must have been allocated
  785.      with `make-alien' or `malloc'.)
  786.  
  787.  
  788. See also with-alien ?, which stack-allocates Aliens.
  789.  
  790.  
  791. 
  792. File: cmu-user.info  Node: Alien Variables, Prev: Alien Operations, Up: Alien Objects, Next: Alien Data Structure Example
  793.  
  794. Alien Variables
  795. ===============
  796.  
  797.  
  798. Both local (stack allocated) and external (C global) Alien variables are
  799. supported.
  800.  
  801. * Menu:
  802.  
  803. * Local Alien Variables::       
  804. * External Alien Variables::    
  805.  
  806.  
  807. 
  808. File: cmu-user.info  Node: Local Alien Variables, Prev: Alien Variables, Up: Alien Variables, Next: External Alien Variables
  809.  
  810. Local Alien Variables
  811. ---------------------
  812.  
  813.  
  814.  
  815.  
  816.  -- Macro: with-alien {(NAME TYPE 
  817.                                   [INITIAL-VALUE])}*
  818.                          {form}*
  819.  
  820.      This macro establishes local alien variables with the specified
  821.      Alien types and names for dynamic extent of the body.  The variable
  822.      NAMES are established as symbol-macros; the bindings have lexical
  823.      scope, and may be assigned with `setq' or `setf'.  This form is
  824.      analogous to defining a local variable in C: additional storage is
  825.      allocated, and the initial value is copied.
  826.      
  827.      `with-alien' also establishes a new scope for named structures and unions.
  828.      Any TYPE specified for a variable may contain name structure or union
  829.      types with the slots specified.  Within the lexical scope of the binding
  830.      specifiers and body, a locally defined structure type FOO can be
  831.      referenced by its name using:
  832.           
  833.           (struct foo)
  834.      
  835.  
  836.  
  837. 
  838. File: cmu-user.info  Node: External Alien Variables, Prev: Local Alien Variables, Up: Alien Variables
  839.  
  840. External Alien Variables
  841. ------------------------
  842.  
  843.  
  844.  
  845. External Alien names are strings, and Lisp names are symbols.  When an
  846. external Alien is represented using a Lisp variable, there must be a way to
  847. convert from one name syntax into the other.  The macros `extern-alien',
  848. `def-alien-variable' and def-alien-routine ? use this conversion
  849. heuristic:
  850.    * Alien names are converted to Lisp names by uppercasing and
  851.      replacing underscores with hyphens.
  852.      
  853.    * Conversely, Lisp names are converted to Alien names by lowercasing and
  854.      replacing hyphens with underscores. 
  855.      
  856.    * Both the Lisp symbol and Alien string names may be separately
  857.      specified by using a list of the form:
  858.           
  859.           (LISP-SYMBOL ALIEN-STRING)
  860.      
  861.  
  862.  
  863.  
  864.  -- Macro: def-alien-variable NAME TYPE
  865.  
  866.      This macro defines NAME as an external Alien variable of the
  867.      specified Alien TYPE.  NAME and TYPE are not evaluated.  The Lisp
  868.      name of the variable (see above) becomes a global Alien variable in
  869.      the Lisp namespace.  Global Alien variables are effectively "global
  870.      symbol macros"; a reference to the variable fetches the contents of
  871.      the external variable.  Similarly, setting the variable stores new
  872.      contents --- the new contents must be of the declared TYPE.
  873.      
  874.      For example, it is often necessary to read the global C variable `errno' to
  875.      determine why a particular function call failed.  It is possible to define
  876.      errno and make it accessible from Lisp by the following:
  877.           
  878.           (def-alien-variable "errno" int)
  879.           
  880.           ;; Now it is possible to get the value of the C variable errno simply by
  881.           ;; referencing that Lisp variable:
  882.           ;;
  883.           (print errno)
  884.      
  885.  
  886.  
  887.  
  888.  -- Macro: extern-alien NAME TYPE
  889.  
  890.      This macro returns an Alien with the specified TYPE which points to
  891.      an externally defined value.  NAME is not evaluated, and may be
  892.      specified either as a string or a symbol.  TYPE is an unevaluated
  893.      Alien type specifier.
  894.  
  895.  
  896.  
  897. 
  898. File: cmu-user.info  Node: Alien Data Structure Example, Prev: Alien Variables, Up: Alien Objects, Next: Loading Unix Object Files
  899.  
  900. Alien Data Structure Example
  901. ============================
  902.  
  903.  
  904. Now that we have Alien types, operations and variables, we can manipulate
  905. foreign data structures.  This C declaration can be translated into the
  906. following Alien type:
  907.      
  908.      struct foo {
  909.          int a;
  910.          struct foo *b[100];
  911.      };
  912.      
  913.       ==
  914.      
  915.      (def-alien-type nil
  916.        (struct foo
  917.          (a int)
  918.          (b (array (* (struct foo)) 100))))
  919.  
  920.  
  921. With this definition, the following C expression can be translated in this way:
  922.      
  923.      struct foo f;
  924.      f.b[7].a
  925.      
  926.       ==
  927.      
  928.      (with-alien ((f (struct foo)))
  929.        (slot (deref (slot f 'b) 7) 'a)
  930.        ;;
  931.        ;; Do something with f...
  932.        )
  933.  
  934.  
  935.  
  936. Or consider this example of an external C variable and some accesses:
  937.      
  938.      struct c_struct {
  939.              short x, y;
  940.              char a, b;
  941.              int z;
  942.              c_struct *n;
  943.      };
  944.      
  945.      extern struct c_struct *my_struct;
  946.      
  947.      my_struct->x++;
  948.      my_struct->a = 5;
  949.      my_struct = my_struct->n;
  950.  
  951. which can be made be manipulated in Lisp like this:
  952.      
  953.      (def-alien-type nil
  954.        (struct c-struct
  955.                (x short)
  956.                (y short)
  957.                (a char)
  958.                (b char)
  959.                (z int)
  960.                (n (* c-struct))))
  961.      
  962.      (def-alien-variable "my_struct" (* c-struct))
  963.      
  964.      (incf (slot my-struct 'x))
  965.      (setf (slot my-struct 'a) 5)
  966.      (setq my-struct (slot my-struct 'n))
  967.  
  968.  
  969.  
  970.  
  971. 
  972. File: cmu-user.info  Node: Loading Unix Object Files, Prev: Alien Data Structure Example, Up: Alien Objects, Next: Alien Function Calls
  973.  
  974. Loading Unix Object Files
  975. =========================
  976.  
  977.  
  978. Foreign object files are loaded into the running Lisp process by
  979. `load-foreign'.  First, it runs the linker on the files and libraries,
  980. creating an absolute Unix object file.  This object file is then loaded
  981. into into the currently running Lisp.  The external symbols defining
  982. routines and variables are made available for future external references
  983. (e.g.  by `extern-alien'.)  `load-foreign' must be run before any of the
  984. defined symbols are referenced.
  985.  
  986. Note that if a Lisp core image is saved (using save-lisp *Note Saving a
  987. Core Image::), all loaded foreign code is lost when the image is
  988. restarted.
  989.  
  990.  
  991.  
  992.  -- Function: load-foreign FILES &key libraries base-file env
  993.  
  994.      FILES is a `simple-string' or list of `simple-string's specifying
  995.      the names of the object files.  LIBRARIES is a list of
  996.      `simple-string's specifying libraries in a format that `ld', the
  997.      Unix linker, expects.  The default value for LIBRARIES is `("-lc")'
  998.      (i.e., the standard C library).  BASE-FILE is the file to use for
  999.      the initial symbol table information.  The default is the Lisp
  1000.      start up code: `path:lisp'.  ENV should be a list of simple strings
  1001.      in the format of Unix environment variables (i.e., `A=B', where A
  1002.      is an environment variable and B is its value).  The default value
  1003.      for ENV is the environment information available at the time Lisp
  1004.      was invoked.  Unless you are certain that you want to change this,
  1005.      you should just use the default.
  1006.  
  1007.  
  1008.  
  1009. 
  1010. File: cmu-user.info  Node: Alien Function Calls, Prev: Loading Unix Object Files, Up: Alien Objects, Next: Step-by-Step Alien Example
  1011.  
  1012. Alien Function Calls
  1013. ====================
  1014.  
  1015.  
  1016. The foreign function call interface allows a Lisp program to call
  1017. functions written in other languages.  The current implementation of the
  1018. foreign function call interface assumes a C calling convention and thus
  1019. routines written in any language that adheres to this convention may be
  1020. called from Lisp.
  1021.  
  1022. Lisp sets up various interrupt handling routines and other environment
  1023. information when it first starts up, and expects these to be in place at
  1024. all times.  The C functions called by Lisp should either not change the
  1025. environment, especially the interrupt entry points, or should make sure
  1026. that these entry points are restored when the C function returns to
  1027. Lisp.  If a C function makes changes without restoring things to the way
  1028. they were when the C function was entered, there is no telling what will
  1029. happen.
  1030.  
  1031. * Menu:
  1032.  
  1033. * alien-funcall::               The alien-funcall Primitive
  1034. * def-alien-routine::           The def-alien-routine Macro
  1035. * def-alien-routine Example::   
  1036. * Calling Lisp from C::         
  1037.  
  1038.  
  1039. 
  1040. File: cmu-user.info  Node: alien-funcall, Prev: Alien Function Calls, Up: Alien Function Calls, Next: def-alien-routine
  1041.  
  1042. The alien-funcall Primitive
  1043. ---------------------------
  1044.  
  1045.  
  1046.  
  1047.  -- Function: alien-funcall ALIEN-FUNCTION &restARGUMENTS
  1048.  
  1049.      This function is the foreign function call primitive: ALIEN-FUNCTION is
  1050.      called with the supplied ARGUMENTS and its value is returned.  The
  1051.      ALIEN-FUNCTION is an arbitrary run-time expression; to call a constant
  1052.      function, use extern-alien *Note External Alien Variables:: or `def-alien-routine'.
  1053.      
  1054.      The type of ALIEN-FUNCTION must be `(alien (function ...))' or
  1055.      `(alien (* (function ...)))', *Note Alien Type Specifiers::.  The function
  1056.      type is used to determine how to call the function (as through it was declared
  1057.      with a prototype.)  The type need not be known at compile time, but only
  1058.      known-type calls are efficiently compiled.  Limitations:
  1059.         * Structure type return values are not implemented.
  1060.         * Passing of structures by value is not implemented.
  1061.      
  1062.  
  1063.  
  1064. Here is an example which allocates a `(struct foo)', calls a foreign
  1065. function to initialize it, then returns a Lisp vector of all the
  1066. `(* (struct foo))' objects filled in by the foreign call:
  1067.      
  1068.      ;;
  1069.      ;; Allocate a foo on the stack.
  1070.      (with-alien ((f (struct foo)))
  1071.        ;;
  1072.        ;; Call some C function to fill in foo fields.
  1073.        (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
  1074.                       (addr f))
  1075.        ;;
  1076.        ;; Find how many foos to use by getting the A field.
  1077.        (let* ((num (slot f 'a))
  1078.               (result (make-array num)))
  1079.          ;;
  1080.          ;; Get a pointer to the array so that we don't have to keep extracting it:
  1081.          (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
  1082.            ;;
  1083.            ;; Loop over the first N elements and stash them in the result vector.
  1084.            (dotimes (i num)
  1085.              (setf (svref result i) (deref (deref a) i)))
  1086.            result)))
  1087.  
  1088.  
  1089. 
  1090. File: cmu-user.info  Node: def-alien-routine, Prev: alien-funcall, Up: Alien Function Calls, Next: def-alien-routine Example
  1091.  
  1092. The def-alien-routine Macro
  1093. ---------------------------
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  -- Macro: def-alien-routine NAME RESULT-TYPE
  1100.                          {(ANAME ATYPE [style])}*
  1101.  
  1102.      This macro is a convenience for automatically generating Lisp interfaces to
  1103.      simple foreign functions.  The primary feature is the parameter style
  1104.      specification, which translates the C pass-by-reference idiom into additional
  1105.      return values.
  1106.      
  1107.      NAME is usually a string external symbol, but may also be a symbol Lisp
  1108.      name or a list of the Lisp name and the foreign name.  If only one name is
  1109.      specified, the other is automatically derived,
  1110.      (*Note External Alien Variables::.)
  1111.      
  1112.      RESULT-TYPE is the Alien type of the return value.  Each remaining
  1113.      subform specifies an argument to the foreign function.  ANAME is the
  1114.      symbol name of the argument to the constructed function (for documentation)
  1115.      and ATYPE is the Alien type of corresponding foreign argument.  The
  1116.      semantics of the actual call are the same as for alien-funcall *Note alien-funcall::.
  1117.      STYLE should be one of the following:
  1118.      :in     
  1119.            specifies that the argument is passed by value.  This is the
  1120.           default.  :in arguments have no corresponding return value from the Lisp
  1121.           function.
  1122.           
  1123.      :out     
  1124.            specifies a pass-by-reference output value.  The type of the
  1125.           argument must be a pointer to a fixed sized object (such as an integer or
  1126.           pointer).  :out and :in-out cannot be used with pointers to arrays,
  1127.           records or functions.  An object of the correct size is allocated, and its
  1128.           address is passed to the foreign function.  When the function returns, the
  1129.           contents of this location are returned as one of the values of the Lisp
  1130.           function. 
  1131.           
  1132.      :copy     
  1133.           
  1134.           is similar to :in, but the argument is copied to a pre-allocated
  1135.           object and a pointer to this object is passed to the foreign routine.
  1136.           
  1137.      :in-out     
  1138.           
  1139.           is a combination of :copy and :out.  The argument is copied to a
  1140.           pre-allocated object and a pointer to this object is passed to the
  1141.           foreign routine.  On return, the contents of this location is returned as an
  1142.           additional value.
  1143.      
  1144.      Any efficiency-critical foreign interface function should be inline expanded by
  1145.      preceding `def-alien-routine' with:
  1146.           
  1147.           (declaim (inline LISP-NAME))
  1148.      
  1149.      In addition to avoiding the Lisp call overhead, this allows pointers,
  1150.      word-integers and floats to be passed using non-descriptor representations,
  1151.      avoiding consing (*Note Non-Descriptor Representations::.)
  1152.  
  1153.  
  1154. 
  1155. File: cmu-user.info  Node: def-alien-routine Example, Prev: def-alien-routine, Up: Alien Function Calls, Next: Calling Lisp from C
  1156.  
  1157. def-alien-routine Example
  1158. -------------------------
  1159.  
  1160.  
  1161. Consider the C function `cfoo' with the following calling convention:
  1162.      
  1163.      cfoo (a, i)
  1164.          char *str;
  1165.          char *a; /* update */
  1166.          int *i; /* out */
  1167.      {
  1168.      /* Body of cfoo. */
  1169.      }
  1170.  
  1171. which can be described by the following call to `def-alien-routine':
  1172.      
  1173.      (def-alien-routine "cfoo" void
  1174.        (str c-string)
  1175.        (a char :in-out)
  1176.        (i int :out))
  1177.  
  1178. The Lisp function `cfoo' will have two arguments (STR and A)
  1179. and two return values (A and I).
  1180.  
  1181. 
  1182. File: cmu-user.info  Node: Calling Lisp from C, Prev: def-alien-routine Example, Up: Alien Function Calls
  1183.  
  1184. Calling Lisp from C
  1185. -------------------
  1186.  
  1187.  
  1188. {There is currently a mechanism for calling Lisp functions from C, but it
  1189. is rather restricted, and is scheduled for replacement.  If you need to call
  1190. Lisp functions from C, contact us and we will let you know what capabilities
  1191. are available in the system you have.  }
  1192.  
  1193.  
  1194. 
  1195. File: cmu-user.info  Node: Step-by-Step Alien Example, Prev: Alien Function Calls, Up: Alien Objects
  1196.  
  1197. Step-by-Step Alien Example
  1198. ==========================
  1199.  
  1200.  
  1201. This section presents a complete example of an interface to a somewhat
  1202. complicated C function.  This example should give a fairly good idea of how to
  1203. get the effect you want for almost any kind of C function.  Suppose you have
  1204. the following C function which you want to be able to call from Lisp in the
  1205. file `test.c':
  1206. struct c_struct
  1207. {
  1208.   int x;
  1209.   char *s;
  1210. };
  1211.  
  1212. struct c_struct *c_function (i, s, r, a)
  1213.     int i;
  1214.     char *s;
  1215.     struct c_struct *r;
  1216.     int a[10];
  1217. {
  1218.   int j;
  1219.   struct c_struct *r2;
  1220.  
  1221.   printf("i = %d\n", i);
  1222.   printf("s = %s\n", s);
  1223.   printf("r->x = %d\n", r->x);
  1224.   printf("r->s = %s\n", r->s);
  1225.   for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
  1226.   r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
  1227.   r2->x = i + 5;
  1228.   r2->s = "A C string";
  1229.   return(r2);
  1230. };
  1231. It is possible to call this function from Lisp using the file `test.lisp'
  1232. whose contents is:
  1233.      
  1234.      ;;; -*- Package: test-c-call -*-
  1235.      (in-package "TEST-C-CALL")
  1236.      (use-package "ALIEN")
  1237.      (use-package "C-CALL")
  1238.      
  1239.      ;;; Define the record c-struct in Lisp.
  1240.      (def-alien-type nil
  1241.          (struct c-struct
  1242.                  (x int)
  1243.                  (s c-string)))
  1244.      
  1245.      ;;; Define the Lisp function interface to the C routine.  It returns a
  1246.      ;;; pointer to a record of type c-struct.  It accepts four parameters:
  1247.      ;;; i, an int; s, a pointer to a string; r, a pointer to a c-struct
  1248.      ;;; record; and a, a pointer to the array of 10 ints.
  1249.      ;;;
  1250.      ;;; The INLINE declaration eliminates some efficiency notes about heap
  1251.      ;;; allocation of Alien values.
  1252.      (declaim (inline c-function))
  1253.      (def-alien-routine c-function
  1254.          (* (struct c-struct))
  1255.        (i int)
  1256.        (s c-string)
  1257.        (r (* (struct c-struct)))
  1258.        (a (array int 10)))
  1259.      
  1260.      ;;; A function which sets up the parameters to the C function and
  1261.      ;;; actually calls it.
  1262.      (defun call-cfun ()
  1263.        (with-alien ((ar (array int 10))
  1264.                     (c-struct (struct c-struct)))
  1265.          (dotimes (i 10)                     ; Fill array.
  1266.            (setf (deref ar i) i))
  1267.          (setf (slot c-struct 'x) 20)
  1268.          (setf (slot c-struct 's) "A Lisp String")
  1269.      
  1270.          (with-alien ((res (* (struct c-struct))
  1271.                            (c-function 5 "Another Lisp String" (addr c-struct) ar)))
  1272.            (format t "Returned from C function.~%")
  1273.            (multiple-value-prog1
  1274.                (values (slot res 'x)
  1275.                        (slot res 's))
  1276.              ;;              
  1277.              ;; Deallocate result after we are done using it.
  1278.              (free-alien res)))))
  1279.  
  1280. To execute the above example, it is necessary to compile the C routine as
  1281. follows:
  1282.      
  1283.      cc -c test.c
  1284.  
  1285. In order to enable incremental loading with some linkers, you may need to say:
  1286.      
  1287.      cc -G 0 -c test.c
  1288.  
  1289. Once the C code has been compiled, you can start up Lisp and load it in:
  1290.      
  1291.      %lisp ;;; Lisp should start up with its normal prompt.
  1292.      
  1293.      ;;; Compile the Lisp file.  This step can be done separately.  You don't have
  1294.      ;;; to recompile every time.
  1295.      * (compile-file "test.lisp")
  1296.      
  1297.      ;;; Load the foreign object file to define the necessary symbols.  This must
  1298.      ;;; be done before loading any code that refers to these symbols.  next block
  1299.      ;;; of comments are actually the output of LOAD-FOREIGN.  Different linkers
  1300.      ;;; will give different warnings, but some warning about redefining the code
  1301.      ;;; size is typical.
  1302.      * (load-foreign "test.o")
  1303.      
  1304.      ;;; Running library:load-foreign.csh...  ;;; Loading object file...
  1305.      ;;; Parsing symbol table...  Warning: "_gp" moved from #x00C082C0
  1306.      to #x00C08460.
  1307.      
  1308.      Warning: "end" moved from #x00C00340 to #x00C004E0.
  1309.      
  1310.      ;;; o.k. now load the compiled Lisp object file.
  1311.      * (load "test")
  1312.      
  1313.      ;;; Now we can call the routine that sets up the parameters and calls the C
  1314.      ;;; function.
  1315.      * (test-c-call::call-cfun)
  1316.      
  1317.      ;;; The C routine prints the following information to standard output.
  1318.      i = 5
  1319.      s = Another Lisp string
  1320.      r->x = 20
  1321.      r->s = A Lisp string
  1322.      a[0] = 0.
  1323.      a[1] = 1.
  1324.      a[2] = 2.
  1325.      a[3] = 3.
  1326.      a[4] = 4.
  1327.      a[5] = 5.
  1328.      a[6] = 6.
  1329.      a[7] = 7.
  1330.      a[8] = 8.
  1331.      a[9] = 9.
  1332.      ;;; Lisp prints out the following information.
  1333.      Returned from C function.
  1334.      ;;; Return values from the call to test-c-call::call-cfun.
  1335.      10
  1336.      "A C string"
  1337.      *
  1338.  
  1339.  
  1340. If any of the foreign functions do output, they should not be called
  1341. from within Hemlock.  Depending on the situation, various strange
  1342. behavior occurs.  Under X, the output goes to the window in which Lisp
  1343. was started; on a terminal, the output will overwrite the Hemlock screen
  1344. image; in a Hemlock slave, standard output is `/dev/null' by default, so
  1345. any output is discarded.
  1346.  
  1347.  
  1348.  
  1349. 
  1350. File: cmu-user.info  Node: Interprocess Communication under LISP, Prev: Alien Objects, Up: Top, Next: Debugger Programmer's Interface
  1351.  
  1352. Interprocess Communication under LISP
  1353. *************************************
  1354.  
  1355.                 Written by William Lott and Bill Chiles
  1356.  
  1357.  
  1358. CMU Common Lisp offers a facility for interprocess communication (IPC)
  1359. on top of using Unix system calls and the complications of that level of
  1360. IPC.  There is a simple remote-procedure-call (RPC) package build on top
  1361. of TCP/IP sockets.
  1362.  
  1363.  
  1364. * Menu:
  1365.  
  1366. * The REMOTE Package::          
  1367. * The WIRE Package::            
  1368. * Out-Of-Band Data::            
  1369.  
  1370.  
  1371. 
  1372. File: cmu-user.info  Node: The REMOTE Package, Prev: Interprocess Communication under LISP, Up: Interprocess Communication under LISP, Next: The WIRE Package
  1373.  
  1374. The REMOTE Package
  1375. ==================
  1376.  
  1377. The `remote' package provides simple RPC facility including interfaces
  1378. for creating servers, connecting to already existing servers, and
  1379. calling functions in other Lisp processes.  The routines for
  1380. establishing a connection between two processes, `create-request-server'
  1381. and `connect-to-remote-server', return WIRE structures.  A wire
  1382. maintains the current state of a connection, and all the RPC forms
  1383. require a wire to indicate where to send requests.
  1384.  
  1385.  
  1386. * Menu:
  1387.  
  1388. * Connecting Servers and Clients::  
  1389. * Remote Evaluations::          
  1390. * Remote Objects::              
  1391. * Host Addresses::              
  1392.  
  1393.  
  1394. 
  1395.